Back to Contents        Previous        Next





8. Errors & Warnings **

You will inevitably meet error messages when you are programming. But this section mainly concerns itself with the facilities Dr Wimp provides for you, the programmer, to include warning and error messages within your coding as a means to help make them more user-friendly. It also revisits the ‘global error trap’ line in the skeleton !RunImage listing, which was first introduced in Section 2.1.

Standard error/warning windows
There are two wimp-functions for producing standard error/warning windows i.e. program action will stop and the ‘error box’ will appear. A mouse-click by the user on an action button (or <return> key or <escape> key press) is needed for the program to proceed.
The first is a PROC which produces a simple error box with just one action button. The second is a FN which can have more than one action button and gives a return value corresponding to which button is pressed.

The first wimp-function (with only one action button) is:

PROCwimp_error(title$,error$,from%,spritename$,spritearea%, button%,altbutton$)


title$
         - is the title to be displayed in the title bar of the error window. Usually, the application name is used and, to assist with this, if
title$
is made a null string then the words appearing will be
<appname>
, where
<appname>
is the same as used in the first parameter of
FNwimp_initialise()
when the application starts
error$
         - is your rquired error/warning message itself. The text is word-wrapped automatically.
from%         -
allows you to prefix the title to suit the error message. If
from%
is 1 then the title is prefixed with “Error from ”. And if it is 2 then the title is prefixed by “Message from ”. If
from%
is 0 no prefix is used.
spritename$ - the sprite name of an additional custom sprite to be added to the error box.
spritearea% - the sprite area containing the above custom sprite name - 1 meaning the wimp-pool.
button%         - controls the default button. If it is 1 then you get a ‘Continue’ button. If it is a 2 then you get a ‘Cancel’ button instead
altbutton$ - allows a button with custom text to be used instead of one of the above default buttons. The string altbutton$ should contain the required button text. If it is not a null string then it will be the button provided and will override whatever value is in button%.
The second wimp-function (allowing multiple action buttons) is:

FNwimp_errorchoice(title$,error$,from%,type%,spritename$,sprite-area%,continue%,cancel%,extrabutton$)

title$          - as above.
error$          - as above.


from%         - as above.


type%         allows you to further tailor the appearance of the error window to suit the type of message. The following standard sprites will appear in the error window, corresponding with the value of type%.


Picture Pics/pic005.png

spritename$ - as above.
spritearea% - as above
continue% - if 1 then a ‘Continue’ button will be provided.
cancel% - if 1 then a ‘Cancel’ button will be provided.
extrabutton$ - allows extra/alternative buttons to be provided. If a null string then no extra buttons will appear. Otherwise, extrabutton$ should be a comma-separated string of the required button texts.
The return from this function is simply a number corresponding with the button pressed by the user. The ‘Continue’ button (if present) always returns 1; the ‘Cancel’ button (if present) always returns 2; and other buttons (if present) return 3, 4, 5 etc. corresponding to the order of their text in extrabutton$.

Here is an example ‘error box’ from this call (made within an application called ‘Calibre’):

errorchoice%=FNwimp_errorchoice(””,”The year needs to be in yyyy format”,2,3,”!calibre”,1,0,0,”Return to application,Quit program”)

Picture Pics/pic006.png
As the parameters continue% and cancel% are both 0, neither the default ‘Continue’ nor ‘Cancel’ button is present. - so the return values of 1 or 2 are not possible. Therefore, clicking ‘Return to application’ will return 3, or clicking ‘Quit application’ will return 4.
Note that the buttons appear from Right to Left in the order ‘Continue’ (if present), ‘Cancel’ (if present), then the items (if any) in order from extrabutton$. The width of the error bax will expand to accomodate all buttons.
If the <return> key is pressed it is the equivalent of pressing the highlighted button (here, ‘Return to application’, so the return will be 3) and if the <Esc> key is pressed it is the equivalent of pressing the button next to it (here, ‘Quit application’, so the return will be 4). If only one button is present then pressing <return> or <Esc> has the same effect and the return will be the same as the return from pressing that only button.


Finally, if your call to PROCwimp_error() or FNwimp_errorchoice() specifies no buttons at all then the error box will default to just a ‘Continue’ button.


The Dr Wimp ‘global error trap’

In Section 2.1 we saw the line:

ON ERROR PROCwimp_error(appname$,REPORT$+” at line“+STR$(ERL),1, ””,0,0,”Quit “+appname$):PROCuser_error: PROCwimp_closedown:END

which is the ‘global error trap’ included in the skeleton !RunImage file (which will also appear in the !RunImage of any application produced by the !Fabricate utility).

As indicated, the role of this line is to react to any errors which may occur during the application run and, having reported what the error is and where, it then takes steps to end the application in an orderly manner - by calling PROCuser_error and then PROCwimp_closedown.

Because this global error trap always leads to quitting the application its main use (hopefully!) is for you, the programmer, whilst developing the application.

PROCwimp_closedown is, in fact, an ‘internal’ function not intended for other uses by the programmer, and it is not in the list of functions in Section 3. (Strictly, it should therefore have a “wint-” prefix - see Section 1.2 - but as it appears in the skeleton !RunImage it is felt that naming it “wimp_” presents less confusion to the beginner.) It is a ‘good housekeeping’ function which closes/removes certain items which may have been opened/created during the program run. For instance, font handles, dynamic areas, messages files, template files. (This internal function is also called by Dr Wimp when you quit the application by normal means.)

It is also worth introducing PROCuser_error at this point. This user-function is only called in the above global error trap line. Its purpose is to give you, the programmer, a convenient place to do your own application-specific ‘good housekeeping’ when something goes wrong and the application needs to end. For instance, possibly the most frequent use might be for closing any files which may be left open because an error occurred during file-manipulation action. This user-function is therefore very useful when developing a program, but another use might be to bring up a message to encourage your users to report any errors to you. Just one word of warning: be very careful to get your coding right within DEF PROCuser_error, otherwise you risk a continuous loop of errors!


Error traps in DrWimp listing
It may assist you in your programming and debugging to know a little about the many errors/warnings which are deliberately ‘trapped’ by the Dr Wimp library. An attempt has been made to distinguish these by the title text used in their error message display.

Here are the most important ones:

RISC OS Version - fatal error if OS Version is less than that specified in FNwimp_initialise. Error message title will be “Error from WIMP”
Window/icon indirection - non-fatal error if attempt is made to change window title or icon text when they are not defined as indirected. Error message title will be “Error from <YourAppName> library”
Icon colour - non-fatal error if attempt is made to change icon colour when the icon is not using the ‘desktop font’. Error message title will be “Error from <YourAppName> library”
Icon caret - non-fatal error if attempt is made to put caret into a non-writable icon. Error message title will be “Error from <YourAppName> library”
Menu from Message file - fatal error if attempt is made to create a menu with the cumulative item text too long. Error message title will be “Error from <YourAppName> library”
Font menus - there are non-fatal warnings if you try to apply to a font-menu any of the many wimp-functions designed to change a menu in some way. For example, you cannot use PROCwimp_putmenutext() to alter a font-menu.
Saving data - DrWimp passes on any “Abort on data transfer” type Wimp error (probably fatal). Error message title will be “Message”
WimpSlot increase - Non-fatal warning if whole of requested increase cannot be done. Error message title will be “Message from <YourAppName> library”
Printing - “Printing abort” Wimp error messages passed on (non-fatal). Error message title will be “Error from <YourAppName> library”
Dynamic areas - Two fatal Wimp errors if you try to change a dynamic area that does not exist or if the change cannot happen for some reason. Also, one non-fatal error if you try to delete a dynamic area which does not exist. Error message titles will be “Error from <YourAppName> library”
Message files - A non-fatal error if you try to initialise more message files than the maximum set
.
Error message title will be “Message from <YourAppName> library”


Iconiser - Non-fatal warning if your intended iconiser sprite has a name longer than 7 characters. Error message title will be “Message from <YourAppName> library”

In addition, there are many wimp-functions where you have the option for an error/warning message to be generated in specific circumstances e.g. if a named file cannot be found.



Inevitably, you will also get error messages which do not fall into the above categories - and these will be picked up by Line 70 of the skeleton !RunImage of !MyApp, which ensures that the error message title will be “Error from <YourAppName>” and that they will all be fatal. They may be the result of your own programming errors or, possibly, due to a bug in Dr Wimp (which you are urged to report if you feel this is the case).

You will, of course, get other error/warning messages arising from your own use of PROCwimp_error and FNwimp_errorchoice and you may feel it worthwhile to arrange for their error message titles to be suitably unique - to make them easily distinguished from the above.






Top of page        Back to Contents        Previous        Next